* @Title: GtkCustomFilter
* @Short_description: Filtering with callbacks
*
- * #GtkCustomFilter is a #GtkFilter that uses a callback to determine whether
- * to include an item or not.
+ * #GtkCustomFilter is a #GtkFilter that uses a callback to determine
+ * whether to include an item or not.
*/
struct _GtkCustomFilter
{
* gtk_custom_filter_new:
* @match_func: (nullable): function to filter items
* @user_data: (nullable): user data to pass to @match_func
- * @user_destroy: destory notify
+ * @user_destroy: destroy notify for @user_data
*
* Creates a new filter using the given @match_func to filter
* items.
*
+ * If @match_func is %NULL, the filter matches all items.
+ *
* If the filter func changes its filtering behavior,
* gtk_filter_changed() needs to be called.
*
* @self: a #GtkCustomFilter
* @match_func: (nullable): function to filter items
* @user_data: (nullable): user data to pass to @match_func
- * @user_destroy: destory notify
+ * @user_destroy: destroy notify for @user_data
*
* Sets (or unsets) the function used for filtering items.
- *
+ *
+ * If @match_func is %NULL, the filter matches all items.
+ *
* If the filter func changes its filtering behavior,
* gtk_filter_changed() needs to be called.
*
* @Short_description: Filtering items
* @See_also: #GtkFilerListModel
*
- * #GtkFilter is the way to describe filters to be used in #GtkFilterListModel.
- *
- * The model will use a filter to determine if it should filter items or not
- * by calling gtk_filter_match() for each item and only keeping the ones
- * visible that the function returns %TRUE for.
+ * A #GtkFilter object describes the filtering to be performed by a
+ * #GtkFilterListModel.
+ *
+ * The model will use the filter to determine if it should include items
+ * or not by calling gtk_filter_match() for each item and only keeping the
+ * ones that the function returns %TRUE for.
*
* Filters may change what items they match through their lifetime. In that
- * case, they can call gtk_filter_changed() which will emit the #GtkFilter:changed
- * signal to notify that previous filter results are no longer valid and that
- * items should be checked via gtk_filter_match() again.
+ * case, they will emit the #GtkFilter:changed signal to notify that previous
+ * filter results are no longer valid and that items should be checked again
+ * via gtk_filter_match().
*
- * GTK provides various premade filter implementations for common filtering
+ * GTK provides various pre-made filter implementations for common filtering
* operations. These filters often include properties that can be linked to
- * various widgets to easily allow searches.
+ * various widgets to easily allow searches.
*
* However, in particular for large lists or complex search methods, it is
* also possible to subclass #GtkFilter and provide one's own filter.
* @self: a #GtkFilter
* @item: (type GObject) (transfer none): The item to check
*
- * Checks if the given @item is matched by the filter or not.
+ * Checks if the given @item is matched by the filter or not.
*
* Returns: %TRUE if the filter matches the item and a filter model should
* keep it, %FALSE if not.
* Gets the known strictness of @filters. If the strictness is not known,
* %GTK_FILTER_MATCH_SOME is returned.
*
- * This value may change after emission of the GtkFilter:changed signal.
+ * This value may change after emission of the #GtkFilter:changed signal.
*
* This function is meant purely for optimization purposes, filters can
* choose to omit implementing it, but #GtkFilterListModel uses it.
* @self: a #GtkFilterListModel
* @incremental: %TRUE to enable incremental filtering
*
- * When incremental filtering is enabled, the filterlistmodel will not run
- * filters immediately, but will instead queue an idle handler that
+ * When incremental filtering is enabled, the GtkFilterListModel will not
+ * run filters immediately, but will instead queue an idle handler that
* incrementally filters the items and adds them to the list. This of course
* means that items are not instantly added to the list, but only appear
* incrementally.
*
* You can use this value to check if @self is busy filtering by
* comparing the return value to 0 or you can compute the percentage
- * of the filter remaining by dividing the return value by
- * g_list_model_get_n_items(gtk_filter_list_model_get_model (self)).
+ * of the filter remaining by dividing the return value by the total
+ * number of items in the underlying model:
+ *
+ * |[
+ * pending = gtk_filter_list_model_get_pending (self);
+ * model = gtk_filter_list_model_get_model (self);
+ * percentage = pending / (double) g_list_model_get_n_items (model);
+ * ]|
*
* Returns: The number of items not yet filtered
**/
* GtkMultiFilter is the base type that implements support for handling
* multiple filters.
*
- * GtkAnyFilter is an implementation of GtkMultiFilter that matches an item
+ * GtkAnyFilter is a subclass of GtkMultiFilter that matches an item
* when at least one of its filters matches.
*
- * GtkEveryFilter is an implementation of GtkMultiFilter that matches an item
+ * GtkEveryFilter is a subclass of GtkMultiFilter that matches an item
* when each of its filters matches.
*/
struct _GtkMultiFilter
/**
* gtk_every_filter_new:
*
- * Creates a new empty "every" filter.
+ * Creates a new empty "every" filter.
* Use gtk_multi_filter_append() to add filters to it.
*
* This filter matches an item if each of the filters added to it
/**
* SECTION:gtkstringfilter
* @Title: GtkStringFilter
- * @Short_description: Filtering by string
+ * @Short_description: Filtering by strings
*
* GtkStringFilter determines whether to include items by looking
* at strings and comparing them to a fixed search term. The strings
projects / gtk4.git / commitdiff